[skip changelog] Fix pull request template markup #1901
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This repository uses a pull request template in order to provide a standardized structure for pull request messages. The template imposes a framework for the organization of the pull request message by providing a section to contain each of the distinct types of important information to be included in the pull request. As should be obvious, the only correct formatting for section headings is heading markup, yet somehow list markup was chosen instead. This collides with the appropriate use of lists within the sections. The template is hereby changed to use the correct markup for headings.
…f PR template This repository uses a pull request template in order to provide a standardized structure for pull request messages. The template includes a link to the project's contributor guide. Previously, this link was at the bottom of the template, separated from the other content by a horizontal rule. One of the unfortunate ambiguities of the Markdown syntax is that the horizontal rule syntax is the same as the "setext" H2 heading syntax, with the differentiation depending on whether the prior line is empty. This results in text intended to be part of the "Other information" section of the PR message instead being formatted as an H2 heading if the contributor does not add an empty line at the end of the "Other information" section. Moving the link to the section of the template that contains a checklist for the PR requirements makes the relevant information readily accessible to the contributor while also avoiding the creation of a formatting trap.
per1234
added
topic: infrastructure
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Please check if the PR fulfills these requirements
See how to contribute
before creating one)
our contributing guidelines
UPGRADING.mdhas been updated with a migration guide (for breaking changes)What kind of change does this PR introduce?
Infrastructure fix
What is the current behavior?
This repository uses a pull request template in order to provide a standardized structure for pull request messages.
There are several problems with the markup used in the template which make the contribution experience unpleasant:
Incorrect heading markup
The template imposes a framework for the organization of the pull request message by providing a section to contain each of the distinct types of important information to be included in the pull request. As should be obvious, the only correct formatting for section headings is heading markup, yet somehow unordered list markup was chosen instead. This collides with the appropriate use of lists within the sections.
Problematic use of horizontal rule
The template includes a link to the project's contributor guide. Previously, this link was at the bottom of the template, separated from the other content by a horizontal rule. One of the unfortunate ambiguities of the Markdown syntax is that the horizontal rule syntax is the same as the "setext-style" H2 heading syntax, with the differentiation depending on whether the prior line is empty. This results in text intended to be part of the "Other information" section of the PR message instead being formatted as an H2 heading if the contributor does not add an empty line at the end of the "Other information" section.
What is the new behavior?
Use the correct markup for headings.
Avoid use of problematic horizontal rule markup.
Does this PR introduce a breaking change, and is titled accordingly?
No breaking change.